ArangoDB with Python: Common Data Operations & Graph Management Cheatsheet

from arango import ArangoClient
from arango import EdgeDefinition # Import necessary class for Graph Management

# Initialize the client connected to your ArangoDB instance.
# We are connecting from the host machine, so use localhost and the mapped port (8529).
client = ArangoClient(hosts='http://localhost:8529')

# Connect to your dedicated application database using your created application user credentials.
# These credentials ('your_application_db', 'your_app_user', 'a_secure_password')
# should correspond to the database and user created following the steps
# outlined in the "User Management" section of the previous article
# (Link to Part 1).
app_database_name = 'your_application_db' # REPLACE with your actual database name
app_username = 'your_app_user'         # REPLACE with your actual username
app_password = 'a_secure_password'     # REPLACE with a strong, secure password

print(f"Attempting to connect to database '{app_database_name}' with user '{app_username}'...")
try:
    db = client.db(app_database_name, username=app_username, password=app_password)
    print("Connection to ArangoDB database successful.")
except Exception as e:
    print(f"Connection failed: {e}")
    # It might be because the database or user doesn't exist, or credentials are wrong.
    # Ensure you have completed the setup and user management steps from Part 1.
    db = None # Set db to None if connection fails

# Assuming 'db' object is successfully created
if db:
    collection_names_to_check = ['my_document_nodes', 'my_relationship_edges', 'some_other_collection']

    print("\n--- Checking Collection Existence ---")
    try:
        for name in collection_names_to_check:
            if db.has_collection(name):
                print(f"  Collection '{name}' exists.")
            else:
                print(f"  Collection '{name}' does not exist.")
    except Exception as e:
        print(f"  Error checking collection existence: {e}")
else:
    print("\nDatabase connection not established. Cannot check collection existence.")

# Assuming 'db' object is successfully created
if db:
    doc_collection_name = 'my_document_nodes'
    edge_collection_name = 'my_relationship_edges'

    print("\n--- Creating Collections ---")

    # Create Document Collection (for nodes)
    if not db.has_collection(doc_collection_name):
        print(f"  Attempting to create document collection '{doc_collection_name}'...")
        try:
            my_document_nodes = db.create_collection(doc_collection_name)
            print(f"  Document collection '{doc_collection_name}' created.")
        except Exception as e:
            print(f"  Failed to create document collection '{doc_collection_name}'. Check permissions: {e}")
    else:
        my_document_nodes = db.collection(doc_collection_name)
        print(f"  Using existing document collection '{doc_collection_name}'.")

    # Create Edge Collection
    if not db.has_collection(edge_collection_name):
        print(f"  Attempting to create edge collection '{edge_collection_name}'...")
        try:
            my_relationship_edges = db.create_collection(edge_collection_name, edge=True)
            print(f"  Edge collection '{edge_collection_name}' created.")
        except Exception as e:
            print(f"  Failed to create edge collection '{edge_collection_name}'. Check permissions: {e}")
    else:
        my_relationship_edges = db.collection(edge_collection_name)
        print(f"  Using existing edge collection '{edge_collection_name}'.")

    # Collection objects are now ready if creation was successful or they existed.
    # my_document_nodes -> used for vertex operations
    # my_relationship_edges -> used for edge operations

else:
     print("\nDatabase connection not established. Cannot create collections.")

# Ensure document and edge collection objects exist
if 'my_document_nodes' in locals() and my_document_nodes and 'my_relationship_edges' in locals() and my_relationship_edges:
    print("\n--- Creating Documents (Nodes) and Edges ---")

    # --- Create Documents (Nodes) ---
    print(f"  Attempting to insert documents into '{my_document_nodes.name}'...")
    docs_data = [
        {'name': 'Person Alice', 'city': 'London', '_key': 'alice'},
        {'name': 'Person Bob', 'city': 'Paris', '_key': 'bob'},
        {'name': 'Company XYZ', 'industry': 'Software', '_key': 'xyz_corp'}
    ]

    try:
        # Use overwrite_mode='ignore' or 'replace' depending on desired behavior if keys already exist
        insert_results_nodes = my_document_nodes.insert_many(docs_data, overwrite_mode='ignore') # Example: Ignore if _key exists
        print(f"  Attempted to insert {len(docs_data)} documents/nodes into '{my_document_nodes.name}'.")
        # insert_results_nodes contains metadata for successful operations

    except Exception as e:
         print(f"  Failed to insert documents into '{my_document_nodes.name}': {e}")

    # --- Create Edges ---
    # We need the FULL IDs (collection/key) for _from and _to attributes.
    # Ensure the nodes exist before creating edges referencing them.
    node_collection_name = my_document_nodes.name # 'my_document_nodes'

    alice_id = f"{node_collection_name}/alice"
    bob_id = f"{node_collection_name}/bob"
    xyz_corp_id = f"{node_collection_name}/xyz_corp"

    # Check if referenced nodes exist before creating edges
    if my_document_nodes.has('alice') and my_document_nodes.has('bob') and my_document_nodes.has('xyz_corp'):

        print(f"\n  Attempting to create edges in '{my_relationship_edges.name}'...")
        edge_data_list = [
            {'_from': alice_id, '_to': bob_id, 'relationship': 'knows', 'strength': 0.8},
            {'_from': alice_id, '_to': xyz_corp_id, 'relationship': 'works_at', 'role': 'Engineer'},
        ]

        try:
            # Insert edges. Use overwrite_mode='ignore' etc. as needed.
            insert_results_edges = my_relationship_edges.insert_many(edge_data_list, overwrite_mode='ignore')
            print(f"  Attempted to insert {len(edge_data_list)} edges into '{my_relationship_edges.name}'.")
            # insert_results_edges contain metadata for successful insertions
        except Exception as e:
             print(f"  Failed to create edges in '{my_relationship_edges.name}'. Ensure _from and _to IDs are correct and collections exist/permissions are granted: {e}")
    else:
        print("\n  Skipping edge creation: Referenced nodes not found.")

else:
    print("\nCannot create documents/edges. Collection objects not available or database not connected.")

# Ensure document and edge collection objects exist and example data is present (e.g., keys 'alice' and edge with key 'knows_alice_bob' if inserted with a key)
if 'my_document_nodes' in locals() and my_document_nodes and 'my_relationship_edges' in locals() and my_relationship_edges:
    print("\n--- Performing CRUD Operations ---")

    # --- Read Data ---
    node_key_to_read = 'alice'
    edge_key_to_read = None # Edge keys are UUIDs by default unless specified. Requires finding the key or using AQL.
                           # Let's try to read the 'alice' node and find an edge connected to it via AQL later.

    print(f"\n  Reading node with key '{node_key_to_read}' from '{my_document_nodes.name}'...")
    try:
        # .get() fetches a document by its _key
        alice_node = my_document_nodes.get(node_key_to_read)
        print(f"    Node: {alice_node}")
    except Exception as e:
        print(f"    Node with key '{node_key_to_read}' not found or error: {e}")
        alice_node = None # Set to None if not found


    # --- Update Data ---
    node_key_to_update = 'alice'
    node_update_data = {'city': 'London, UK', 'tags': ['person', 'developer']}
    if my_document_nodes.has(node_key_to_update):
        print(f"\n  Updating node with key '{node_key_to_update}' in '{my_document_nodes.name}'...")
        try:
            # .update() merges update_data into the existing document
            update_result = my_document_nodes.update(node_key_to_update, node_update_data)
            print(f"    Node updated.")
        except Exception as e:
            print(f"    Failed to update node with key '{node_key_to_update}': {e}")
    else:
        print(f"\n  Node with key '{node_key_to_update}' not found, skipping update.")

    # --- Delete Data ---
    node_key_to_delete = 'bob' # We'll delete the 'bob' node
    if my_document_nodes.has(node_key_to_delete):
        print(f"\n  Deleting node with key '{node_key_to_delete}' from '{my_document_nodes.name}'...")
        try:
            # .delete() removes a document by its _key. ignore_missing=True prevents error if already gone.
            my_document_nodes.delete(node_key_to_delete, ignore_missing=True)
            print(f"    Node with key '{node_key_to_delete}' deleted.")
            # Reminder: Edges connected to/from 'bob' (like 'alice' -> 'bob' 'knows') are now dangling unless handled.
            # Let's manually delete the edge between alice and bob next.

        except Exception as e:
             print(f"    Failed to delete node with key '{node_key_to_delete}': {e}")
    else:
         print(f"\n  Node with key '{node_key_to_delete}' not found, skipping deletion.")

    # --- Delete an Edge (Manually) ---
    # We need to find the edge referencing the deleted node 'bob'
    # This often requires querying, as edge keys are not always semantic.
    # Let's use AQL to find the edge from alice to bob
    alice_id = f"{my_document_nodes.name}/alice"
    bob_id = f"{my_document_nodes.name}/bob"

    find_edge_query = f"""
    FOR edge IN {my_relationship_edges.name}
        FILTER edge._from == '{alice_id}' AND edge._to == '{bob_id}'
        LIMIT 1 # Assuming only one such edge
        RETURN edge._key
    """
    print(f"\n  Finding edge key for edge from '{alice_id}' to '{bob_id}'...")
    try:
         cursor = db.aql.execute(find_edge_query)
         edge_key_to_delete_manual = next(cursor, None) # Get the first key, or None if not found

         if edge_key_to_delete_manual:
             print(f"  Found edge key to delete: '{edge_key_to_delete_manual}'.")
             print(f"  Attempting to delete edge with key '{edge_key_to_delete_manual}' from '{my_relationship_edges.name}'...")
             try:
                 my_relationship_edges.delete(edge_key_to_delete_manual, ignore_missing=True)
                 print(f"    Edge with key '{edge_key_to_delete_manual}' deleted.")
             except Exception as e:
                 print(f"    Failed to delete edge with key '{edge_key_to_delete_manual}': {e}")
         else:
              print("  Edge from alice to bob not found (perhaps already deleted or never created).")

    except Exception as e:
         print(f"  Error finding edge to delete: {e}")


    # Other CRUD operations (more complex queries, batch operations) are often done with AQL or specific collection methods
    # E.g. my_document_nodes.delete_many(['key1', 'key2'], ignore_missing=True)

else:
    print("\nCannot perform CRUD operations. Collections not available or database not connected.")

# Ensure 'db' object is available and doc collection exists with data
if db and 'my_document_nodes' in locals() and my_document_nodes and db.has_collection(my_document_nodes.name):
    collection_name_for_aql = my_document_nodes.name

    # Example AQL Query: Find all persons located in 'London'
    query = f"""
    FOR doc IN {collection_name_for_aql}
        FILTER doc.name LIKE 'Person %' AND doc.city == 'London, UK'
        RETURN {{ name: doc.name, city: doc.city }}
    """
    print(f"\n--- Running Basic AQL Query on '{collection_name_for_aql}' ---")
    print(f"Query:\n{query}")

    try:
        # db.aql.execute returns a cursor, which streams results
        cursor = db.aql.execute(query)
        print(f"\n  Results from AQL query:")
        count = 0
        print("  --- Start AQL Results ---")
        for document in cursor:
            print(f"  {document}")
            count += 1
        print("  --- End AQL Results ---")
        print(f"  AQL query finished. Found {count} matching documents.")

    except Exception as e:
        print(f"  Failed to execute basic AQL query. Check query syntax, collection names, and permissions: {e}")

else:
    print("\nCannot run basic AQL queries. Collection not available or database not connected.")

# Ensure the collection objects used in definitions exist
if 'my_document_nodes' in locals() and my_document_nodes and 'my_relationship_edges' in locals() and my_relationship_edges:
    node_collection_name = my_document_nodes.name # 'my_document_nodes'
    edge_collection_name = my_relationship_edges.name # 'my_relationship_edges'

    print("\n--- Defining Edge Definitions ---")
    try:
        # Example: Edges from 'my_document_nodes' to 'my_document_nodes' using 'my_relationship_edges'
        # Represents relationships *within* the node collection, like 'knows'.
        person_relation_definition = EdgeDefinition(
            edge_collection=edge_collection_name,
            from_collections=[node_collection_name],
            to_collections=[node_collection_name]
        )

        # Example 2: If you had a 'companies' node collection, and 'works_at' edge collection:
        # company_relation_definition = EdgeDefinition(
        #     edge_collection='works_at',
        #     from_collections=[node_collection_name], # e.g., Person nodes
        #     to_collections=['companies'] # e.g., Company nodes
        # )

        # Collect all definitions for the graph
        graph_edge_definitions = [
            person_relation_definition,
            # Add other definitions here
            # company_relation_definition,
        ]
        print(f"  Defined {len(graph_edge_definitions)} edge definitions.")

    except Exception as e:
         print(f"  Failed to define Edge Definitions. Ensure collection names are correct: {e}")
         graph_edge_definitions = [] # Clear definitions if error occurring
else:
    print("\nCannot define Edge Definitions. Necessary collection objects not available or database not connected.")

# Ensure 'db' object and 'graph_edge_definitions' exist
if db and 'graph_edge_definitions' in locals() and graph_edge_definitions:
    graph_name = 'my_application_graph' # REPLACE with your desired graph name

    # Optional: Check if the graph already exists
    if not db.has_graph(graph_name):
        print(f"\n--- Creating Formal Graph '{graph_name}' ---")
        try:
            # create_graph requires a list of EdgeDefinition objects
            # orphan_collections allows including vertex collections not connected by any edge definition
            my_graph = db.create_graph(
                graph_name,
                graph_edge_definitions,
                orphan_collections=[] # Add names of collections here that should be vertices but have no edges defined yet
            )
            print(f"  Graph '{graph_name}' created successfully.")

        except Exception as e:
            # This might fail if collections don't exist, permissions are insufficient, or graph name exists
            print(f"  Failed to create graph '{graph_name}': {e}")
            my_graph = None # Clear graph object if creation fails
    else:
        my_graph = db.graph(graph_name)
        print(f"\n--- Graph '{graph_name}' already exists. Using existing graph. ---")
        # If graph exists and structure needs updating, use methods like graph.add_edge_definition

# 'my_graph' object is now ready if creation was successful or it existed.
else:
     print("\nCannot create graph. Database connection not established or edge definitions are not defined.")

# Ensure 'db' object is available
if db:
    print("\n--- Listing Graphs ---")
    try:
        graphs = db.graphs()
        if graphs:
            print("  All Graphs in the database:")
            for graph in graphs:
                print(f"  - Graph: {graph.name}")
        else:
            print("  No formal graphs found in the database.")

    except Exception as e:
        print(f"  Failed to list graphs: {e}")
else:
    print("\nDatabase connection not established. Cannot list graphs.")

# Ensure 'my_graph' object is available and represents an existing graph
if 'my_graph' in locals() and my_graph:
    print(f"\n--- Modifying Graph '{my_graph.name}' ---")

    # Example: Define a new edge definition to potentially add (assuming 'new_edge_type_coll' exists)
    # new_edge_coll_name = 'new_edge_type_coll'
    # from_coll_name = 'my_document_nodes'
    # to_coll_name = 'another_node_coll'
    # new_edge_def = EdgeDefinition(new_edge_coll_name, [from_coll_name], [to_coll_name])

    # print(f"  Attempting to add a hypothetical edge definition...")
    # try:
    #     # Requires the collections to actually exist
    #     my_graph.add_edge_definition(new_edge_def)
    #     print(f"  Edge definition using '{new_edge_coll_name}' added.")
    # except Exception as e:
    #     print(f"  Failed to add edge definition: {e}")


    # Example: Remove an edge definition
    # print(f"\n  Attempting to remove edge definition 'my_relationship_edges'...")
    # try:
    #     my_graph.delete_edge_definition(
    #          edge_collection='my_relationship_edges', # Specify the edge collection name
    #          drop_collection=False # Set to True to drop the edge collection and its data too (BE CAREFUL!)
    #         )
    #     print(f"  Edge definition using 'my_relationship_edges' removed.")
    # except Exception as e:
    #      print(f"  Failed to remove edge definition: {e}")


     # Example: Add an orphan collection (assuming 'standalone_nodes' collection exists)
     # orphan_coll_name = 'standalone_nodes'
     # if db.has_collection(orphan_coll_name):
     #     print(f"\n  Attempting to add orphan collection '{orphan_coll_name}'...")
     #     try:
     #         my_graph.add_vertex_collection(orphan_coll_name)
     #         print(f"  Orphan collection '{orphan_coll_name}' added.")
     #     except Exception as e:
     #         print(f"  Failed to add orphan collection '{orphan_coll_name}': {e}")
     # else:
     #      print(f"\n  Collection '{orphan_coll_name}' does not exist. Cannot add as orphan.")


     # Example: Remove an orphan collection
     # orphan_coll_name_to_remove = 'standalone_nodes'
     # print(f"\n  Attempting to remove orphan collection '{orphan_coll_name_to_remove}'...")
     # try:
     #      my_graph.remove_vertex_collection(
     #           orphan_coll_name_to_remove,
     #           drop_collection=False # Set to True to drop the collection too (BE CAREFUL!)
     #         )
     #      print(f"  Orphan collection '{orphan_coll_name_to_remove}' removed.")
     # except Exception as e:
     #      print(f"  Failed to remove orphan collection '{orphan_coll_name_to_remove}': {e}")


else:
    print("\nGraph object not available. Cannot add/remove definitions or orphan collections.")

# Ensure 'db' object is available
if db:
    graph_name_to_drop = 'my_application_graph' # The name of the graph to drop

    print(f"\n--- Dropping Graph '{graph_name_to_drop}' ---")
    try:
        # Check if graph exists first
        if db.has_graph(graph_name_to_drop):
            # Delete the graph definition.
            # IMPORTANT: drop_collections=False (default) ONLY removes the graph definition.
            # Data in the collections used by the graph is NOT deleted.
            # Set drop_collections=True to delete the collections and their data as well (EXTREME CAUTION!).
            db.delete_graph(graph_name_to_drop, drop_collections=False)
            print(f"  Graph '{graph_name_to_drop}' definition deleted (collections and data retained).")

        else:
             print(f"  Graph '{graph_name_to_drop}' not found. Nothing to delete.")


    except Exception as e:
        print(f"  Failed to drop graph '{graph_name_to_drop}': {e}")
else:
    print("\nDatabase connection not established. Cannot drop graph.")

# Ensure 'db' object is available and your graph exists
if db and db.has_graph('my_application_graph'):
    graph_name_for_query = 'my_application_graph' # The graph you created

    # Ensure the start node exists
    start_node_key = 'alice' # Use a key from data created earlier
    start_node_id = f"my_document_nodes/{start_node_key}" # Full ID format

    if db.collection('my_document_nodes').has(start_node_key):

        # Example AQL Graph Query: Perform a graph traversal
        # Find nodes reachable from 'alice' within 1 to 2 steps in 'my_application_graph'
        # using any edge direction ('ANY').
        query = f"""
        FOR v, e, p IN 1..2 ANY '{start_node_id}' GRAPH '{graph_name_for_query}'
            OPTIONS {{ uniqueVertices: 'graph' }} # Ensure each vertex is returned only once
            RETURN {{ vertex: v, edge: e, path_edges: p.edges[*].relationship }} # Return vertex, connecting edge, and relationship types in the path
        """

        print(f"\n--- Running AQL Graph Query on '{graph_name_for_query}' ---")
        print(f"Query:\n{query}")

        try:
            # db.aql.execute returns a cursor
            cursor = db.aql.execute(query)
            print(f"\n  Results from AQL graph query:")
            count = 0
            print("  --- Start Graph Query Results ---")
            for result in cursor:
                print(f"  {result}")
                count += 1
            print("  --- End Graph Query Results ---")
            print(f"  AQL graph query finished. Found {count} graph elements matching the traversal.")

        except Exception as e:
            # Ensure graph and collections exist, start_node_id is correct, and permissions are granted.
            print(f"  Failed to execute AQL graph query: {e}")

    else:
        print(f"\nStart node '{start_node_key}' not found. Cannot run graph query.")

else:
    print("\nCannot run AQL graph queries. Graph or database connection not available.")